CD ROM Paradise Collection 4

home *** CD-ROM | disk | FTP | other *** search

/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / program / 4th86_v4.zip / INTRO.4TH < prev next >

Wrap

Text File | 1994-01-02 | 21KB | 535 lines

4th_86 version 4.01 INTRO.4TH page 1 ( November 1993 - 4th_86 version 4.01 - MFB ) Description of system ===================== In an attempt to keep this introduction short and easy to digest, the description has been split into several files. It will help if you print these to use as reference -- but this file along with the built in HELP tutorial will get you started. Read also DISK.NDX for a description of all issued files and their function. a) INTRO.4TH this file b) CELCIUS.WLK a walkthrough of the procedure for writing a short program b) WHY.UCC a description of the objectives and philosophy of 4th_86 c) GLOSSARY a functional summary of most of the principal WORDS d) MANUAL a manual doubling as a tutorial e) DISK.NDX a last minute addition listing the files provided. The file TUTORIAL.TXT is not meant to be printed. It is loaded into 4th_86 when the command HELP is issued and will then become a hands-on interactive tutorial. It contains many control codes designed to display parts of the system as the tutorial progresses and these may confuse your printer if you attempt to print it. The files EXAMPLE1.4TH EXAMPLE2.4TH etc are required as part of the interactive tutorial. They are standard ascii and can be printed if you wish -- but there is little purpose in doing so. Configuration ============= 4th_86 will function either as a windowed or a full screen DOS application within Windows 3.1. There is little advantage in doing this. 4th_86 is originally intended to run directly under DOS. The only configuration needed is to use your standard DOS editor to edit the files EDITR.BAT and ASMBL.BAT. EDITR.BAT currently contains the statement \dos\edit %1. EDIT is the DOS 5.x editor and you should replace this with the name you type as a command to execute your own favorite DOS editor. You can either include a complete drive and path specification with it -- or you can ensure that your PATH statement will allow DOS to find your editor. Note that if your DOS editor is a "memory hog" [ or you have too many TSRs loaded ] the DEMONSTRATION 4th_86 may produce an "out of memory" error due to it being an over-complete configuration. 4th_86 version 4.01 INTRO.4TH page 2 You must also make sure that a copy of COMMAND.COM is in the ROOT directory [ this is essential ] of the disk you are running 4th_86 from. If you do not do this, 4th_86 will not be able to shell to DOS to execute your editor. You should also add a line similar to SET COMSPEC = C:\DOS\COMMAND.COM to your autoexec.bat file. ASMBL.BAT currently contains command lines for Microsoft MASM, LINK, and EXE2BIN. If you use the Microsoft MASM assembler -- no configuration is needed to this file. If you use some other assembler- linker combination; you will have to decide for yourself the equivalent commands to put in ASMBL.BAT. Both these batch files can be tested without using 4th_86. Simply type ASMBL xxxx where xxxx is the name of any [ COM format compatible ] ASM file on your disk. The file should be assembled into a binary file xxxx.BIN. Likewise to test EDITR simply type EDITR xxxx where xxxx is any text file. Your editor should load the file xxxx and make it ready for editing. While 4th_86 can use EGA and CGA graphics -- graphics formats are not needed to use 4th_86 in normal text mode. Video Page Swapping =================== The issue version 4.01 of 4th_86 uses video page swapping, and it is assumed you will be able to access video pages 0 1 and 2. The demonstration version however has page swapping disabled to minimise the chance of hardware incompatability problems. The purpose of page swapping is to give any functions which shell to DOS [ such as REDIT, SYS, BLOAD, INT3 ] their own display screens in order that the previous 4th_86 video display can be left undisturbed and returned to. When page swapping is implemented, 4th_86 will work on page 1 whilst DOS-shell functions will work in page 0. Things were arranged this way as some DOS editors may not be capable of working other than in page 0. When you understand the system a bit more you can set it up for page swapping or constant page0. This is controlled by a variable IVPAGE. IVPAGE in the demonstration version is set to 0. To implement page swapping set IVPAGE to 1 on the command line when you initiate 4TH86DEM. In other words, from the DOS prompt type 4TH86DEM 1 IVPAGE ! < return > 4th_86 version 4.01 INTRO.4TH page 3 Help Tutorial ============= The HELP tutorial is contained in a file called TUTORIAL.TXT. In the demonstration version of 4th_86 the tutorial [ windowed ] mode is entered automatically on startup. If you want to disable this -- either delete or rename TUTORIAL.TXT. If 4th_86 can't find TUTORIAL.TXT to load it will give an error message and bypass the color and windowing code. Of course -- this will also render the HELP command ineffective. Format of Source files ====================== All ASM and 4TH source is standard ascii and can be edited with any text editor. Because an extended ascii character 179 is used in some of the 4TH source code to line up if -- then -- else etc; it is desirable that the editor you use should display ascii 179 as the correct asciii-graphics character -- a vertical bar. Making use of EDITR.BAT ======================= One of the major features of 4th_86 is the ability to **automatically** "shell" from 4th_86 in to your favorite DOS editor. More than this however -- if the file you are editing is 4th source code -- you can have it loaded automatically each time you exit your editor and return to 4th_86. The magic word is REDIT -- but first you have to define the name of the file xxxx that you wish to use. To do this you type USING xxxx. You need do this only once -- the name will remain in effect until you redefine it with USING. Let's say you were not happy with the file EXAMPLE1.4th and you wanted to do some work on it. You wish to edit it; then load it into 4th_86 to test it; then edit it a second time to correct it further ; then reload it into 4th_86 again -- and so on repetitively until you are satisfied. First enter the command USING EXAMPLE1.4TH. Then type REDIT. If you have configured EDITR.BAT properly you should now be shelled out to your editor looking at EXAMPLE1.4TH -- and no longer in 4th_86. Do not change anything for the moment -- simply exit from your editor. The updated EXAMPLE1.4TH will be saved to disk -- you will find yourself back in 4th_86 -- and you will see the file EXAMPLE1.4TH being loaded. Repeat the process by again typing REDIT [ no need to type USING etc ]. Again -- as you exit your editor and re-enter 4th_86; the file EXAMPLE1.4TH will be loaded ** a second time **. 4th_86 version 4.01 INTRO.4TH page 4 This is not really what you want -- multiple definitions of the same words. In fact -- unless you have included in the file the statement ON REDEFINE -- 4th_86 will halt and ask you if you really want to redefine the words. If you include ON REDEFINE the words will be redefined without any warning query. Using FORGET when REDITing ========================== There is a technique whereby you can REDIT multiple times without redefining words. You start every 4th source file with the statements FORGET STRT : STRT ; OFF REDEFINE And in addition -- immediately before you type USING EXAMPLE1.4TH [ or whatever source file you name ] you must also type : STRT ; What is happening is that you put a "bookmark" arbitarily named STRT into 4th_86 before you do any editing. You do this by defining a "null" word [ ie it contains no code -- and does nothing ] called STRT. Note that the actual word STRT has no significance. Any word can be used so long as it doesn't clash with an existing word in 4th_86. As with USING you only need do this once. Now every time you exit your editor -- and EXAMPLE1.4TH starts to load -- the first thing it does is to FORGET the "bookmark" -- ** and all the words following it **. It effectively clears out all the results of the previous load. It then redefines the bookmark STRT -- and proceeds to load the EXAMPLE1.4TH definitions in to a cleaned out load area. Using PRINTLOAD =============== If you find that a 4th source file encounters a load problem half way through -- you will want to see it displayed on screen as it loads, in order that you can detect the point at which it fails. To do this, add ON PRINTLOAD to the above three statements. If you don't want the text displayed -- include OFF PRINTLOAD. Using EDIT and RELOAD ===================== The word REDIT in fact executes EDIT and then RELOAD in sequence. They can be used independently if you wish. EDIT will shell to your editor; but will not do any load when you exit the editor. Similarly RELOAD will not shell to your editor but will load the file that has previously been defined by USING. 4th_86 version 4.01 INTRO.4TH page 5 You would use EDIT rather than REDIT if you wanted to edit a non-4th-source file -- such as TUTORIAL.TXT -- or an ASM file which had to be BLOADed [ Binary loaded ] . Using FLOAD =========== To load a 4th source file [ say TEST.4TH ] into 4th_86 you can either type FLOAD TEST.4TH -- or you can type " TEST.4TH" LOAD. Note that there is no requirement that 4th source files carry the suffix 4TH. They can have any suffix -- or none -- so long as the code is valid 4th code. Using BLOAD ============ It is recommended that you skip over this paragraph if you are a beginner. It will be a long time before you have cause to use BLOAD -- if ever. It is however a feature of 4th_86 and is described here for anyone who is interested. BLOAD is an "intelligent" command rather like REDIT. It is used to load MASM source code into 4th_86 -- by automatically shelling to DOS and calling MASM; LINK; EXE2BIN to create a xxx.BIN file; which it then loads. It is further "intelligent" in that it first compares the date and time of any existing BIN file with the corresponding ASM file. Only if the ASM file is of a later date than the BIN file is the assemble etc carried out. Otherwise the existing BIN file will be loaded as-is. To "force" an assembly -- simply delete any existing BIN file. A pointer called HEAD is maintained in all Forths which points to the address at which all new code [ whether FLOADed or BLOADed ] is to be placed. To ensure that MASM assembles the ASM file at the corresponding ORG value -- the first thing BLOAD does as it shells to MASM is to write a two line file called ORGFILE to disk. The user need not worry about ORGFILE -- it is written and used automatically. All ASM files contain the statement INCLUDE ORGFILE and this re-sets the ORG equ 100H statement to ORG equ ( HEAD @ ) A file called TEST.ASM is provided to demonstrate the structure needed -- and to allow you to try out the BLOAD command. After you have BLOADed it -- use DDICT to verify the words -- and use DD to disassemble them. Verify that the words execute and print the intended messages. 4th_86 version 4.01 INTRO.4TH page 6 BLOAD and In-Line assembly ========================== Version 4.01 has full in line 8086 assembly -- and a disassembler. Whereas 4th definitions are started with a colon -- assembly routines are started with the word CODE CODE TEST pop ax cmp ax,23h jz found blah blah blah jmp done | found yak yak yak | done more yak blah labels ; or CODE TEST pop ax cmp ax,23h ifz yak yak yak else blah blah blah then more yak blah ; Look at some of the 4th source code on disk -- and also the files MASMTST and MASM.TST for illustrations. The point being made here is that you may never need to use BLOAD. Unless you are writing a complicated assembly module to BLOAD, Inline assembly will be much easier. Logical operators AND, OR, XOR ============================== 4th_86 allows code to be entered in either FORTH words -- or in ASSEMBLY language. Normally there is no duplication as 4th_86 words have been chosen not to conflict with comparable assembly mnemonics. For example -- SHR is an assembly word. SHR8 and ->L are comparable 4th_86 words. In the case of AND, OR and XOR the same words are used for both assembly useage and 4th_86 useage. 4th_86 resolves the confusion by testing a variable called CODEFLAG which is "set" when ASSEMBLY mode is in operation -- and not set in FORTH mode. 4th_86 version 4.01 INTRO.4TH page 7 : and codeflag @ if /and else and then ; : or codeflag @ if /or else or then ; : xor codeflag @ if /xor else xor then ; This functions without any problems -- but there may be situations where you wish to over-ride the CODEFLAG decision and determine specifically which mode to use. If you specifically want to use the assembly mnemonic then use /AND. If you specifically want to use the 4th_86 word use -AND. Turnkey Demonstration Files =========================== Several demonstration files are included. FP_DEMO.COM shows the use of floating point; while HILBERT.COM, MAND.COM etc show the use of EGA graphics. See the file DISK.NDX for a description -- or just run them and watch what happens. The source code for several of these demos is included along with the necessary image files APPS.IMG and APPSFP.IMG to create standalone demos. To create HILBERT.COM for example -- simply fire up 4TH_86FP.COM and then type FLOAD HILCOM.DEM. By examining the demonstration source files [ xxx.DEM and xxx.4TH] you can see how to create your own turnkey programs. DOS Command Line parameters =========================== 4th_86 allows words to be included on the command line. For example you could create HILBERT.COM from the DOS prompt by typing at the DOS prompt 4TH86FP FLOAD HILCOM.DEM < return >. This can be extremely useful as the above can be included in a DOS batch file as all DEM files end by returning to DOS naturally. File BUILDEM.BAT ---------------- 4th_86FP fload smith.dem 4th_86FP fload square.dem 4th_86FP fload hilcom.dem 4th_86FP fload fpoint.dem 4th_86FP fload 4demo.dem 4th_86FP fload mand.dem ( ** NOTE ** because of the 10 second delay built into the exit to DOS for the DEMO file the above is only a fast option with the full non- demo version. It will however work. ) 4th_86 version 4.01 INTRO.4TH page 8 You could also type something like 4TH86FP 1 IVPAGE ! UNSPLIT USING EXAMPLE1.4TH EDIT < return > Though there is little to be gained by doing so as opposed to entering the secondary commands one at a time at the 4th_86 prompt. Use of INT3 =========== If 4th_86 is started from within some debugger utility [ for example by typing DEBUG 4TH_86FP.COM < return > and then typing G at the Debug prompt ] you will at any time be able to use the Forth word INT3 to activate the debugger. This should hardly be necessary as 4th_86 has its own very effective debugging words -- but it can be useful to examine memory etc. To return from the DOS debugger, start execution at address 200H. The usual command is G=200 Hard copy from screen ====================== The normal DOS command shift-PrtScr will dump the existing screen to printer. The normal dos ctl-P will toggle on and off continuous echo of screen output to printer. If ctl-P is activated to printer; ascii text disk files can be printed while in 4th_86 by using the 4th_86 word TYPE. The word COPY is not implemented in 4th_86 -- nor is the "filename" PRN. Extensability ============= Remember that one principle of FORTH is that the system can be "extended" by simply defining new words that you need -- and then FSAVEing or SAVESYSing the resulting file. If you felt that you needed some new words such as COPY or RENAME or DELETE -- or indeed complicated windowing techniques -- you can add them at any time. The word SYNONYM will allow you to rename words if you wish to adhere to some alternatives that you regard as more conventional or "standard". Alternatively you can simply issue another defenition -- : NEW_WORD OLD_WORD ; 4th_86 version 4.01 INTRO.4TH page 9 If you don't *like* the way an existing definition works -- you can redefine that defenition without affecting the way all existing words which use [ and continue to use ] the original definition function. You *can* also redefine in a retrospective way so that existing words now use your new definition instead of the one they were designed to interface with. This is inadvisable -- as without the complete source code you will not know the global effects of your changes on existing code. Not all words can be disassembled using DD -- because they have been OMITted from the dictionary either as embodying "restricted" code -- or because they have no purpose other than as intermediate words used in building up other more meaningful words. The disassembler for example contains dozens of words KIND01 KIND02 KIND03 etc -- which have no use individually in any application and are therefore OMITted from the dictionary to conserve space. A disassembly which can not find a word will print OOPS in place of it's name. Further Tutorials ================= If I get evidence that reasonable interest is being shown in the BBS version of 4th_86, I will prepare more organised and detailed TUTORIAL.TXT files and EXAMPLEnn.4TH files to go with them. For the moment use what HELP is exists -- look at the provided source code -- and read the additional examples in MANUAL. Above all -- practice as a hands-on interactive exercise. Further Versions ================ While version 4.01 provides several separate 64K segments for dictionary; cross compile; etc -- it still restricts the code segment to 64K maximum. The next version [ which is now functional ] extends the code segment to 128K with the possibility of even further extensions. Work is still in progress to adapt this extended addressing into a restructured overall philosophy. Version 4.01 is essentially intended as a learning environment -- and the present 64K limit on code segment does not really impose any severe limitations. Extending this 64K for its own sake -- and incurring EXE file structures in isolation of a total re-design of any clearly defined objective would serve little purpose. It is hoped that users of version 4.01 will provide feedback of their impressions. Read WHY.UCC for a further discussion of system philosophy.